Release 10.1A: OpenEdge Development:
Messaging and ESB

Error and condition handling

This section provides information about handling of errors and conditions with the 4GL-JMS API.

From the point of view of the 4GL programmer, there are two types of errors and conditions, programming errors and run-time conditions:

A programming error is an erroneous sequence of calls to the 4GL-JMS API, or the calling of the API with invalid parameters. Typically, programming errors should not occur in a deployed application. An example of a programming error is an attempt by the application to make a TextMessage call such as setText procedure, setLongText procedure, and appendText procedure in a StreamMessage. Programming errors should be tracked down and fixed at development time. The primary source of information for that phase is the 4GL-JMS API. (See Appendix A "4GL-JMS API Reference.")
A run-time condition is an event that disturbs the normal flow of the application. Such events can occur in a deployed application, so the 4GL programmer should try to handle them programmatically. Examples of run-time conditions include attempts to connect to a JMS server that is not currently running, and attempts to subscribe to a topic without the proper authorization. For information about programmatically handling run-time conditions, refer to SonicMQ API Reference , which is installed in sonicmq_docs\sonicmq_api under the SonicMQ installation directory (open index.html in this directory, or access SonicMQ API Reference from the SonicMQ Documentation Portal).

A second criterion for classifying errors and conditions is whether the problem is reported by the 4GL-JMS implementation synchronously or asynchronously:

A problem is reported synchronously if it occurs and is detected while the 4GL application is executing a 4GL-JMS API call.
A problem is reported asynchronously when it comes from the asynchronous error reporting system of the JMS server (OnException Events) or from the 4GL-JMS mechanism that delivers messages asynchronously to the 4GL client.

Programming errors are usually reported synchronously. Run-time conditions are reported either synchronously or asynchronously.

Handling errors

To manage errors use the setErrorHandler procedure and setNoErrorDisplay procedure.

Synchronously reported errors and conditions

Errors are reported synchronously when something goes wrong at a method call. The problems can be either programming errors or run-time conditions. Examples include attempts to publish to an unauthorized topic or attempts to receive from a nonexistent queue.

A 4GL API function reports problems synchronously by returning an Unknown value (?).

Some programming errors are not detected by the 4GL-JMS API but rather by the 4GL 
interpreter. For example, an attempt to call the setText procedure in a StreamMessage causes 
error 6456: 
 



  

  
    
 Procedure message.p has no entry point for setText. (6456) 

To report a problem synchronously, the 4GL-JMS API internal procedure calls:

RETURN ERROR <error-message>

This call raises an error condition at the caller. The caller can use regular 4GL techniques to handle the error: a NO–ERROR phrase or an ON ERROR block, coupled with checking the RETURN–VALUE value to obtain the error message. If an application uses the NO–ERROR phrase, it must check the STATUS–ERROR:error flag to determine whether a problem has occurred.

By default, every synchronously reported error or condition is displayed by the 4GL-JMS API, which calls:

MESSAGE <error-message> VIEW-AS ALERT-BOX.

This mechanism allows a quick analysis and resolution of the problem at development time. At deployment time, however, the application developer might want to handle problems programmatically and prevent the message from appearing. Calling the setNoErrorDisplay procedure in the Session object suppresses the message display.

Note: Message objects inherit the display/noDisplay property from the session that created them. However, after a message is created, it is independent of the session. The setNoErrorDisplay procedure must be called in the Message object itself to change this property.

Asynchronously reported conditions

Typically, problems reported asynchronously are run-time conditions, such as the failure of the SonicMQ Broker or the failure of communication between the OpenEdge Adapter for SonicMQ and the SonicMQ Broker. (See OpenEdge Application Server: Administration .) Another example is the failure to send an automatic reply (the message handler is set with a reply message, but the SonicMQ server fails to send the reply).

The error condition is reported in a TextMessage, with several possible CHAR message properties in the message header: exception, errorCode, linkedException–1, linkedException–2… linkedException–n (where n is a number of additional exceptions linked to the main exception). Use the getPropertyNames function to get a list of properties in the error message header. See Appendix B, "Messaging Examples" for an example.

The application should handle problems of this type programmatically by creating a Message Consumer object and passing it to the setErrorHandler procedure in the Session object. If an application does not set an error handler, a default error handler displays the error message and the properties in alert boxes.

Note: An application must call the beginSession procedure before creating the error-handling Message Consumer object and calling the setErrorHandler procedure.

Run-time conditions

Typically, run-time exceptions are generated by the Java-JMS code on the server. In such cases, the format of the error message obtained from the RETURN–VALUE is:

<java-exception>:<error-message>.

The 4GL programmer can look up the types of exceptions thrown by SonicMQ and handle some of them programmatically. The most typical run-time error conditions are connection and authorization failures.

Connection and communication failures

The most common run-time error condition is a connection failure. The beginSession procedure, which creates the connection to the OpenEdge Adapter for SonicMQ and the JMS server, reports connection failures synchronously by calling:

RETURN ERROR <error-message>.

The error can result from a failure to connect either to the OpenEdge Adapter for SonicMQ or to the JMS server. If the connection to the JMS server fails, the format of the error message is:

<java-exception>:<error-message>.

A communication failure that occurs after a successful connection might be detected:

Synchronously (for example, when the application is trying to publish a message).
Asynchronously through the error handler.

It might take several minutes for the timeout mechanism to trigger a communication failure event. To detect potential communication failures more quickly, use the setPingInterval procedure (a SonicMQ extension) to instruct the OpenEdge Adapter for SonicMQ to actively ping the SonicMQ Broker every n seconds.

Message handler errors and conditions

A message-handling procedure is an arbitrary 4GL program, and the programmer is free to use any 4GL technique to handle problems that occur during the processing of a message. However, the following issues and limitations exist:

Message handlers should handle ERROR, STOP, and QUIT conditions and not propagate them. An unhandled condition is considered a programming error.
Since the message handler returns control to the 4GL-JMS implementation and the message handler cannot raise a condition, there must be a mechanism to allow the message handler to communicate problems to the rest of the 4GL application. You can use the setApplicationContext procedure call to pass a 4GL procedure handle to the Message Consumer object. The message handler can obtain the procedure handle by calling the getApplicationContext function in the Message Consumer object and can then make the appropriate internal procedure calls.
As mentioned in the "Message acknowledgement, forwarding, and recovery" section, the message handler can call the setNoAcknowledge procedure of the Message Consumer to prevent the message from being acknowledged in a session that is not transacted for receiving.
Calling WAIT–FOR is allowed inside a message handler, but no further messages from that Session object are received until the message handler returns.
The following recursive calls from the message handler into the 4GL-JMS API of the same Session object are considered programming errors: deleteSession procedure, deleteConsumer procedure, and recover procedure. There are no restrictions on calling these API entries of another Session object.

Interrupts

An interrupt (CTRL+C on UNIX platforms or CTRL+BREAK on Microsoft platforms) while a 4GL-JMS call is executing can cause the call to return either a 4GL STOP condition or an ERROR condition, depending on the exact timing. The 4GL-JMS implementation guarantees that partial messages will not be sent or received as the result of an interrupt.

OpenEdge Adapter for SonicMQ failure

If communication with the OpenEdge Adapter for SonicMQ is lost, or if the OpenEdge Adapter for SonicMQ shuts down while the 4GL client is performing a WAIT–FOR or waitForMessages procedure statement, a 4GL STOP condition is raised.

If communication with the OpenEdge Adapter for SonicMQ is lost, or if the OpenEdge Adapter for SonicMQ shuts down while the 4GL-JMS implementation is actively trying to communicate to it (for example, when the 4GL application calls the publish procedure or the subscribe procedure), an ERROR or STOP condition is raised, depending on the exact point at which the failure is discovered.